/*!
 * \file ITrdNotifySink.h
 * \project	WonderTrader
 *
 * \author Wesley
 * \date 2020/03/30
 * 
 * \brief 交易通知接收器接口头文件
 * 
 * 定义了WonderTrader系统中交易通知接收器的核心接口，
 * 主要功能包括：
 * 1. 接收成交回报通知
 * 2. 接收订单状态变化通知
 * 3. 接收持仓变化通知
 * 4. 接收交易通道状态通知
 * 5. 接收委托确认通知
 * 
 * 该接口为交易系统提供统一的事件通知机制，
 * 确保各个模块能够及时获取交易状态变化信息。
 */
#pragma once
#include <stdint.h>
#include "../Includes/WTSMarcos.h"

NS_WTP_BEGIN

/**
 * @class ITrdNotifySink
 * @brief 交易通知接收器接口
 * 
 * 交易通知接收器接口定义了交易系统中各种事件的回调方法：
 * 1. 成交回报 - 当订单成交时触发
 * 2. 订单回报 - 当订单状态发生变化时触发
 * 3. 持仓更新 - 当持仓发生变化时触发
 * 4. 通道状态 - 当交易通道连接状态变化时触发
 * 5. 委托确认 - 当委托提交后收到确认时触发
 * 
 * 实现此接口的类可以接收并处理各种交易事件，
 * 实现交易状态的实时监控和处理。
 */
class ITrdNotifySink
{
public:
	/**
	 * @brief 成交回报回调
	 * @param localid 本地订单ID
	 * @param stdCode 标准合约代码
	 * @param isBuy 是否为买入方向
	 * @param vol 成交数量
	 * @param price 成交价格
	 * 
	 * 当订单发生成交时触发此回调，提供成交的详细信息。
	 * 系统会根据成交信息更新持仓和资金状态。
	 */
	virtual void on_trade(uint32_t localid, const char* stdCode, bool isBuy, double vol, double price) = 0;

	/**
	 * @brief 订单回报回调
	 * @param localid 本地订单ID
	 * @param stdCode 标准合约代码
	 * @param isBuy 是否为买入方向
	 * @param totalQty 订单总数量
	 * @param leftQty 剩余未成交数量
	 * @param price 订单价格
	 * @param isCanceled 是否已撤销，默认为false
	 * 
	 * 当订单状态发生变化时触发此回调，包括部分成交、全部成交、撤销等状态。
	 * 通过剩余数量可以判断订单的执行进度。
	 */
	virtual void on_order(uint32_t localid, const char* stdCode, bool isBuy, double totalQty, double leftQty, double price, bool isCanceled = false) = 0;

	/**
	 * @brief 持仓更新回调
	 * @param stdCode 标准合约代码
	 * @param isLong 是否为多头持仓
	 * @param prevol 更新前持仓数量
	 * @param preavail 更新前可用持仓数量
	 * @param newvol 更新后持仓数量
	 * @param newavail 更新后可用持仓数量
	 * @param tradingday 交易日
	 * 
	 * 当持仓发生变化时触发此回调，提供持仓变化的详细信息。
	 * 包括持仓数量和可用数量的变化，用于持仓管理和风控。
	 */
	virtual void on_position(const char* stdCode, bool isLong, double prevol, double preavail, double newvol, double newavail, uint32_t tradingday) {}

	/**
	 * @brief 交易通道就绪回调
	 * 
	 * 当交易通道连接成功并准备就绪时触发此回调。
	 * 表示可以开始进行交易操作。
	 */
	virtual void on_channel_ready() = 0;

	/**
	 * @brief 交易通道断开回调
	 * 
	 * 当交易通道连接断开或失效时触发此回调。
	 * 系统应停止交易操作并尝试重新连接。
	 */
	virtual void on_channel_lost() = 0;

	/**
	 * @brief 委托确认回调
	 * @param localid 本地订单ID
	 * @param stdCode 标准合约代码
	 * @param bSuccess 委托是否成功
	 * @param message 返回消息，通常包含错误信息
	 * 
	 * 当委托提交后收到交易所或柜台的确认时触发此回调。
	 * 如果委托失败，message参数会包含失败原因。
	 */
	virtual void on_entrust(uint32_t localid, const char* stdCode, bool bSuccess, const char* message){}
};

NS_WTP_END